(SST) ShlWAPI.pas Version 1.08
Developer Reference
(SST)ShlWAPI SHFormatDateTime Function
Converts the values of a TFileTime record/structure into a user friendly date and time text.
Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).
Syntax
function SHFormatDateTime(puft : PFileTime; pdwFlags : PDWORD; pszBuf : LPSTR; cchBuf : UINT) : Integer;
Parameters
puft [in] Address of, or pointer to a TFileTime record/structure with the encoded date and/or time to format/convert.
pdwFlags [in/out] A pointer to a DWORD variable, that on entry contains the flags that specify the desired date and time format. If the function succeeds, this variable is set to a value corresponding to the flags actually used to format the string.
One or a combination of the following flags are acceptable on input:
FDTF_SHORTTIME (= $00000001) The time in the returned string will be formatted according to the user/system locale specific short time settings. This flag may not be specified in combination with the FDTF_LONGTIME flag.
FDTF_SHORTDATE (= $00000002) The date in the returned string will be formatted according to the user/system locale specific short date settings. A typical example, using the French locale, is "30/07/2017" The flag may not be specified in combination with the FDTF_LONGDATE flag.
FDTF_DEFAULT (= $00000003) Combines the short date with the short time format (= FDTF_SHORTDATE OR FDTF_SHORTTIME).
FDTF_LONGDATE (= $00000004) The date in the returned string will be formatted according to the user/system locale specific long date settings. A typical example, using the German locale, is "Montag, 30 Juli 2017" The flag may not be specified in combination with the FDTF_SHORTDATE flag.
FDTF_SHORTTIME (= $00000008) The time in the returned string will be formatted according to the user/system locale specific long time settings. A typical example, using the US English locale, is "7:59:42 AM" This flag may not be specified in combination with the FDTF_LONGTIME flag.
FDTF_RELATIVE (= $00000010) The date and/or time are given relative to the current date and/or time. Typical examples (using the US English locale) are "13 minutes ago" and "Today, June 16, 2017". This flag appears to be ignored under Windows 98 SE and NT 4.0 with IE 5.0.
FDTF_LTRDATE (= $00000100) Inserts left-to-right reading order (question) marks. This and the FDTF_RTLDATE flag are mutually exclusive.
FDTF_RTLDATE (= $00000200) Inserts right-to-left reading order (question) marks. This and the FDTF_LTRDATE flag are mutually exclusive.
FDTF_NOAUTOREADINGORDER (= $00000400) Reading order (question) marks are omitted. This flag should not be specified in combination with the FDTF_LTRDATE and/or FDTF_RTLDATE flags.
pszBuf [out] A pointer to the buffer into which the function should write the zero-terminated date and/or time string.
cchBuf [in] The size of the buffer pointed to by pszBuf, in number of characters. Note, that the required buffer size depends on the specified formatting flags.
Return Values
If the function succeeds, the return value is the number of characters (single or double byte, depending on which version was called) written to the buffer pointed to in pszBuf. If the function fails, the return value is 0.
Remarks
When called withoug specifying the FDTF_NOAUTOREADINGORDER flag, the function left-pads the individual date and time, text components with reading order (question) marks.
Unlike many other Windows, API functions, SHFormatDateTime does not return the required buffer size if zero (0) or an inadequate size is specified the cchBuf parameter.
This function is esxported by name as of ShlWAPI.dll version 6.0 under Windows Vista, but according to the declaration and documentation it is available as of ShlWAPI.dll 5.0 under Windows 2000. However, information on how the function(s) can be called under versions prior to Vista was not available at the time this article was written.
Nonetheless, we were able to ascertain that the function is exported by ordinals 353 and 354 (for the ANSI and wide character/Unicode version respectively) down to and including Windows NT 4.0 with Internet Explorer 5.0 and Windows 98 SE. These versions, though, (presumably) only support an unknown subset of the flag combinations that can be specified in the second parameter (pdwFlags). For example, the FDTF_RELATIVE flag appears not to be supported.
As the function is also supported under Windows 98 SE, it stands to reason that it may also be supported under Windows 95 and 98, provided Internet Explorer 5.0 is installed. Unfortunately we did not have access to such systems and therefore this remains an assumption.
Example
PROCEDURE TForm4.TestShlWAPISHFormatDateTime(Sender : TObject);
//Important ! Without the FDTF_NOAUTOREADINGORDER flag,
//SHFormatDateTime inserts question marks before all parts of
//the string.
VAR currentdatetime : TFileTime;
VAR datetimestrbuf : ARRAY [0 .. 128] OF CHAR;
VAR datetimewcharbuf : ARRAY [0 .. 128] OF WideChar;
VAR fmtflags : DWORD;
VAR bufsize : UINT;
VAR apiretval : INTEGER;
VAR newinfoline : STRING;

   BEGIN
FillChar(currentdatetime, SizeOf(currentdatetime), #0);
FillChar(datetimestrbuf, Length(datetimestrbuf), #0);
FillChar(datetimewcharbuf, Length(datetimewcharbuf), #0);
fmtflags := 0;
bufsize := 0;
apiretval := 0;
newinfoline := '';

GetSystemTimeAsFileTime(currentdatetime);
fmtflags := FDTF_LONGDATE OR FDTF_LONGTIME; // OR FDTF_NOAUTOREADINGORDER; // OR FDTF_RELATIVE;
bufsize := Length(datetimestrbuf);
newinfoline := 'SHFormatDateTime called with current date and time : ';
Memo1.Lines.Add(newinfoline);
apiretval := SHFormatDateTime(@currentdatetime, @fmtflags, datetimestrbuf, bufsize);
newinfoline := IntToStr(apiretval) + ', ';
newinfoline := newinfoline + datetimestrbuf;
Memo1.Lines.Add(newinfoline);

fmtflags := FDTF_LONGDATE OR FDTF_LONGTIME OR FDTF_RELATIVE OR FDTF_NOAUTOREADINGORDER;
bufsize := Length(datetimewcharbuf);
apiretval := SHFormatDateTimeW(@currentdatetime, @fmtflags, datetimewcharbuf, bufsize);
newinfoline := datetimewcharbuf;
newinfoline := IntToStr(apiretval) + ', ' + newinfoline;
Memo1.Lines.Add(newinfoline);

Memo1.Lines.Add('');
   END;
Called on June 16, 2017, the above code produced the following output
SHFormatDateTime called with current date and time :
41, ?Friday, ?June ?16, ?2017, ??7:25:40 AM
33, Today, June 16, 2017, 7:25:40 AM
Requirements
Unit: Declared and imported in (SST)ShlWAPI.pas
Library: (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode: Implemented as ANSI (SHFormatDateTime and SHFormatDateTimeA) and Unicode (SHFormatDateTimeW) functions.
Min. ShlWAPI.dll version according to MS SDK doc.: 5.0
Min. ShlWAPI.dll version based on SST research: 5.0
Min. OS version(s) according to Microsoft SDK doc.: Windows 2000, Windows 2000 Server, Windows Server 2003, Windows XP
Min. OS version(s) according to SST research.: Windows NT 4.0 with IE 5.0, Windows 98 SE, Windows 2000
See Also
SHFormatDateTime, StrFromTimeInterval, StrFormatByteSizeA, StrFormatByteSizeW, StrFormatByteSize64A, StrFormatByteSizeEx, StrFormatKBSize, StrToInt, StrToInt64Ex, StrToIntEx
 
Windows APIs: SHFormatDateTime, StrFromTimeInterval, GetSystemTimeAsFileTime, StrFormatByteSize, StrFormatByteSize64A, StrFormatByteSizeEx, StrFormatKBSize, StrToInt, StrToInt64Ex, StrToIntEx


Document/Contents version 1.00
Page/URI last updated on 07.12.2023 		 
Copyright © Stoelzel Software Technologie (SST) 2010 - 2017 		Suggestions and comments mail to:
webmaster@stoelzelsoftwaretech.com